home *** CD-ROM | disk | FTP | other *** search
Wrap
Text File | 1996-05-01 | 18.5 KB | 565 lines | [ TEXT/MPS ]
{ File: CodeFragments.p Contains: Public Code Fragment Manager Interfaces. Version: Technology: System 7 and System 8 Release: Universal Interfaces 3.0d3 on Copland DR1 Copyright: © 1984-1996 by Apple Computer, Inc. All rights reserved. Bugs?: If you find a problem with this file, send the file and version information (from above) and the problem description to: Internet: apple.bugs@applelink.apple.com AppleLink: APPLE.BUGS } { • =========================================================================================== The Code Fragment Manager API ============================= } {$IFC UNDEFINED UsingIncludes} {$SETC UsingIncludes := 0} {$ENDC} {$IFC NOT UsingIncludes} UNIT CodeFragments; INTERFACE {$ENDC} {$IFC UNDEFINED __CODEFRAGMENTS__} {$SETC __CODEFRAGMENTS__ := 1} {$I+} {$SETC CodeFragmentsIncludes := UsingIncludes} {$SETC UsingIncludes := 1} {$IFC UNDEFINED __TYPES__} {$I Types.p} {$ENDC} {$IFC UNDEFINED __FILES__} {$I Files.p} {$ENDC} {$IFC FOR_SYSTEM8_PREEMPTIVE } {$IFC UNDEFINED __KERNEL__} {$I Kernel.p} {$ENDC} {$IFC UNDEFINED __FILEMANAGERTYPES__} {$I FileManagerTypes.p} {$ENDC} {$IFC UNDEFINED __TEXTOBJECTS__} {$I TextObjects.p} {$ENDC} {$ENDC} {$PUSH} {$ALIGN MAC68K} {$LibExport+} { § =========================================================================================== Universal types and constants ============================= } {$IFC FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE } { ---------------------------------------------------------------------------- These declarations are for System 7 and all System 8 execution environments. } CONST kCFragResourceType = 'cfrg'; kCFragResourceID = 0; kCFragLibraryFileType = 'shlb'; kCFragAllFileTypes = $FFFFFFFF; TYPE CFragArchitecture = OSType; CONST kPowerPCCFragArch = 'pwpc'; kMotorola68KCFragArch = 'm68k'; kAnyCFragArch = $3F3F3F3F; {$IFC GENERATINGPOWERPC } kCompiledCFragArch = 'pwpc'; {$ENDC} {$IFC GENERATING68K } kCompiledCFragArch = 'm68k'; {$ENDC} TYPE CFragVersionNumber = UInt32; CONST kNullCFragVersion = 0; kWildcardCFragVersion = $FFFFFFFF; TYPE CFragUsage = UInt8; CONST kImportLibraryCFrag = 0; { Standard CFM import library. } kApplicationCFrag = 1; { Macintosh application. } kDropInAdditionCFrag = 2; { Private extension to an application or library. } kIsCompleteCFrag = 0; { A "base" fragment, not an update. } kFirstCFragUpdate = 1; { The first update, others are numbered 2, 3, ... } kCFragGoesToEOF = 0; TYPE CFragLocatorKind = UInt8; CONST kMemoryCFragLocator = 0; { Container is already addressable. } kDataForkCFragLocator = 1; { Container is in a file's data fork. } kResourceCFragLocator = 2; { Container is in a file's resource fork. } { -------------------------------------------------------------------------------------- A 'cfrg' resource consists of a header followed by a sequence of variable length members. The constant kDefaultCFragNameLen only provides for a legal ANSI declaration and for a reasonable display in a debugger. The actual name field is cut to fit. There may be "extensions" after the name, the memberSize field includes them. The general form of an extension is a 16 bit type code followed by a 16 bit size in bytes. Only one standard extension type is defined at present, it is used by SOM's searching mechanism. } TYPE CFragUsage1UnionPtr = ^CFragUsage1Union; CFragUsage1Union = RECORD CASE INTEGER OF { ! Meaning differs depending on value of "usage". } 0: ( appStackSize: UInt32; { If the fragment is an application. (Not used by CFM!) } ); END; CFragUsage2UnionPtr = ^CFragUsage2Union; CFragUsage2Union = RECORD CASE INTEGER OF { ! Meaning differs depending on value of "usage". } 0: ( appSubdirID: SInt16; { If the fragment is an application. } ); END; CFragWhere1UnionPtr = ^CFragWhere1Union; CFragWhere1Union = RECORD CASE INTEGER OF { ! Meaning differs depending on value of "where". } 0: ( spaceID: UInt32; { If the fragment is in memory. (Actually an AddressSpaceID.) } ); 1: ( forkKind: OSType; { If the fragment is in an arbitrary byte stream fork. } ); END; CFragWhere2UnionPtr = ^CFragWhere2Union; CFragWhere2Union = RECORD CASE INTEGER OF { ! Meaning differs depending on value of "where". } 0: ( forkInstance: UInt16; { If the fragment is in an arbitrary byte stream fork. } ); END; CONST kDefaultCFragNameLen = 16; TYPE CFragResourceMemberPtr = ^CFragResourceMember; CFragResourceMember = RECORD architecture: CFragArchitecture; reservedA: UInt16; { ! Must be zero! } reservedB: SInt8; { ! Must be zero! } updateLevel: SInt8; currentVersion: CFragVersionNumber; oldDefVersion: CFragVersionNumber; uUsage1: CFragUsage1Union; uUsage2: CFragUsage2Union; usage: SInt8; where: SInt8; offset: UInt32; length: UInt32; uWhere1: CFragWhere1Union; uWhere2: CFragWhere2Union; extensionCount: UInt16; { The number of extensions beyond the name. } memberSize: UInt16; { Size in bytes, includes all extensions. } name: PACKED ARRAY [0..15] OF UInt8; { ! Actually a sized PString. } END; CFragResourceExtensionHeaderPtr = ^CFragResourceExtensionHeader; CFragResourceExtensionHeader = RECORD extensionKind: UInt16; extensionSize: UInt16; END; CFragResourceSearchExtensionPtr = ^CFragResourceSearchExtension; CFragResourceSearchExtension = RECORD header: CFragResourceExtensionHeader; libKind: OSType; qualifiers: SInt8; { ! Actually four PStrings. } END; CONST kCFragResourceSearchExtensionKind = $30EE; TYPE CFragResourcePtr = ^CFragResource; CFragResource = RECORD reservedA: UInt32; { ! Must be zero! } reservedB: UInt32; { ! Must be zero! } reservedC: UInt16; { ! Must be zero! } version: UInt16; reservedD: UInt32; { ! Must be zero! } reservedE: UInt32; { ! Must be zero! } reservedF: UInt32; { ! Must be zero! } reservedG: UInt32; { ! Must be zero! } reservedH: UInt16; { ! Must be zero! } memberCount: UInt16; firstMember: CFragResourceMember; END; CONST kCurrCFragResourceVersion = 1; TYPE CFragConnectionID = ^LONGINT; CFragClosureID = ^LONGINT; CFragContainerID = ^LONGINT; CFragContextID = ^LONGINT; CFragLoadOptions = UInt32; CONST kLoadCFrag = $0001; { Try to use existing copy, load if not found. } kFindCFrag = $0002; { Try find an existing copy, don't load if not found. } kPrivateCFragCopy = $0005; { Load a new private copy. } kUnresolvedCFragSymbolAddress = 0; TYPE CFragSymbolClass = UInt8; CONST kCodeCFragSymbol = 0; kDataCFragSymbol = 1; kTVectorCFragSymbol = 2; kTOCCFragSymbol = 3; kGlueCFragSymbol = 4; {$ENDC} { § =========================================================================================== System 7 Services (Deprecated in System 8) ========================================== } {$IFC FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED } { --------------------------------------------------------------------------------- These declarations are for System 7 and the System 8 cooperative environment, but should be avoided under System 8. Better alternatives exist for System 8. } FUNCTION GetSharedLibrary(libName: Str63; archType: CFragArchitecture; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0001, $AA5A; {$ENDC} FUNCTION GetDiskFragment({CONST}VAR fileSpec: FSSpec; offset: UInt32; length: UInt32; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0002, $AA5A; {$ENDC} FUNCTION GetMemFragment(memAddr: UNIV Ptr; length: UInt32; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0003, $AA5A; {$ENDC} FUNCTION CloseConnection(VAR connID: CFragConnectionID): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0004, $AA5A; {$ENDC} FUNCTION FindSymbol(connID: CFragConnectionID; symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0005, $AA5A; {$ENDC} FUNCTION CountSymbols(connID: CFragConnectionID; VAR symCount: LONGINT): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0006, $AA5A; {$ENDC} FUNCTION GetIndSymbol(connID: CFragConnectionID; symIndex: LONGINT; VAR symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr; {$IFC NOT GENERATINGCFM} INLINE $3F3C, $0007, $AA5A; {$ENDC} {$ENDC} { § =========================================================================================== System 8 Services (Not available in System 7) ============================================= } {$IFC FOR_SYSTEM8_PREEMPTIVE } { --------------------------------------------------------------------------------- These declarations are for all System 8 execution environments, but not System 7. } CONST kPatchCFragUpdateLevel = 255; kByteStreamCFragLocator = 3; kNamedFragmentCFragLocator = 4; kNamedLibraryCFragLocator = 4; { !!! Remove in D12! } kPrivilegedCFragMask = $0010; { ! May be removed in the future! } kResidentCFragMask = $0020; { ! May be removed in the future! } kTreatCFragAsLibraryMask = $0040; { Used in GetXyzFragment to recognize by name too. } kPrivilegedCFragFlag = $0010; { !!! Remove in D12! } kResidentCFragFlag = $0020; { !!! Remove in D12! } kMainCFragSymbolIndex = -1; kInitCFragSymbolIndex = -2; kTermCFragSymbolIndex = -3; TYPE CFragRegisteredFileInfoPtr = ^CFragRegisteredFileInfo; CFragRegisteredFileInfo = RECORD fileRef: FSObjectRef; fileType: OSType; nestingDepth: ItemCount; END; CONST kCFragRegisteredFileInfoVersion = $00010001; TYPE CFragCompatibility = UInt8; CONST CFragBothCompatible = 0; CFragClientTooOld = 1; CFragProviderTooOld = 2; TYPE CFragShortVersionPair = UInt32; FUNCTION CFragCheckCompatibility(clientPreferredVersion: UInt32; clientOldImpVersion: UInt32; providerCurrentVersion: UInt32; providerOldDefVersion: UInt32): ByteParameter; C; FUNCTION CFragCheckShortCompatibility(clientVersions: UInt32; providerVersions: UInt32): ByteParameter; C; FUNCTION CFragHasFileLocation(where: ByteParameter): BOOLEAN; C; FUNCTION CFragHasUnresolvedImports(connID: CFragConnectionID): BOOLEAN; C; FUNCTION CFragPrepareNamedFragment(fragName: Str63; usage: ByteParameter; archType: CFragArchitecture; preferredVersion: CFragVersionNumber; oldestVersion: CFragVersionNumber; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: LogicalAddress; optErrMsg: TextObject): OSStatus; C; FUNCTION CFragPrepareFromDiskFork(fileSpec: FSObjectRef; forkTag: FSForkType; forkInstance: ItemCount; offset: ByteCount; length: ByteCount; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: LogicalAddress; optErrMsg: TextObject): OSStatus; C; FUNCTION CFragPrepareFromMemory(fragAddr: LogicalAddress; length: ByteCount; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: LogicalAddress; optErrMsg: TextObject): OSStatus; C; FUNCTION CFragCloseConnection(VAR connID: CFragConnectionID): OSStatus; C; FUNCTION CFragFindNamedSymbol(connID: CFragConnectionID; symName: Str255; VAR symAddr: LogicalAddress; VAR symClass: CFragSymbolClass): OSStatus; C; FUNCTION CFragCountSymbols(connID: CFragConnectionID; VAR symCount: ItemCount): OSStatus; C; FUNCTION CFragGetIndexedSymbol(connID: CFragConnectionID; symIndex: SInt32; VAR symName: Str255; VAR symAddr: LogicalAddress; VAR symClass: CFragSymbolClass): OSStatus; C; FUNCTION CFragGetFileSpec(connectionID: CFragConnectionID; VAR fileSpec: FSObjectRef): OSStatus; C; FUNCTION CFragGetFragmentName(connectionID: CFragConnectionID; VAR name: Str63): OSStatus; C; FUNCTION CFragRegisterFileFragments(processID: KernelProcessID; fileSpec: FSObjectRef; fileType: OSType; nestingDepth: ItemCount): OSStatus; C; FUNCTION CFragUnregisterFileFragments(processID: KernelProcessID; fileSpec: FSObjectRef; fileType: OSType; nestingDepth: ItemCount): OSStatus; C; FUNCTION CFragGetRegisteredFiles(processID: KernelProcessID; requestedCount: ItemCount; VAR totalCount: ItemCount; infoVersion: PBVersion; VAR registeredFiles: CFragRegisteredFileInfo): OSStatus; C; {$ENDC} { § =========================================================================================== Initialization & Termination Routines ===================================== ----------------------------------------------------------------------------------------- A fragment's initialization and termination routines are called when a new incarnation of the fragment is created or destroyed, respectively. Exactly when this occurs depends on what kinds of section sharing the fragment has and how the fragment is prepared. Import libraries have at most one incarnation per process. Fragments prepared with option kPrivateCFragCopy may have many incarnations per process. The initialization function is passed a pointer to an initialization information structure and returns an OSErr. If an initialization function returns a non-zero value the entire closure of which it is a part fails. The CFragInitBlock type has different visible parts under System 7 and System 8, but is of course the same internally. The C prototype for an initialization function is: pascal OSErr CFragInitFunction ( const CFragInitBlock * initBlock ); The termination procedure takes no parameters and returns nothing. The C prototype for a termination procedure is: pascal void CFragTermProcedure ( void ); } {$IFC FOR_OPAQUE_SYSTEM_DATA_STRUCTURES } { -------------------------------------------------------------------------------------- These declarations are the preferred form for System 8, hiding implementation details. } TYPE CFragOpaqueInitBlockPtr = ^CFragOpaqueInitBlock; CFragOpaqueInitBlock = RECORD processID: KernelProcessID; closureID: CFragClosureID; connectionID: CFragConnectionID; reservedA: ARRAY [0..7] OF UInt32; END; CFragInitBlock = CFragOpaqueInitBlock; CFragInitBlockPtr = ^CFragInitBlock; {$ELSEC} { -------------------------------------------------------------------------------------- These declarations are for System 7. They may be used in System 8 but expose details. } TYPE CFragSystem7MemoryLocatorPtr = ^CFragSystem7MemoryLocator; CFragSystem7MemoryLocator = RECORD address: LogicalAddress; length: UInt32; inPlace: BOOLEAN; reservedA: SInt8; { ! Must be zero! } reservedB: UInt16; { ! Must be zero! } END; CFragSystem7DiskFlatLocatorPtr = ^CFragSystem7DiskFlatLocator; CFragSystem7DiskFlatLocator = RECORD fileSpec: FSSpecPtr; offset: UInt32; length: UInt32; END; { ! This must have a file specification at the same offset as a disk flat locator! } CFragSystem7SegmentedLocatorPtr = ^CFragSystem7SegmentedLocator; CFragSystem7SegmentedLocator = RECORD fileSpec: FSSpecPtr; rsrcType: OSType; rsrcID: SInt16; reservedA: UInt16; { ! Must be zero! } END; CFragSystem7LocatorPtr = ^CFragSystem7Locator; CFragSystem7Locator = RECORD where: SInt32; CASE INTEGER OF 0: ( onDisk: CFragSystem7DiskFlatLocator; ); 1: ( inMem: CFragSystem7MemoryLocator; ); 2: ( inSegs: CFragSystem7SegmentedLocator; ); END; CFragSystem7InitBlockPtr = ^CFragSystem7InitBlock; CFragSystem7InitBlock = RECORD contextID: CFragContextID; closureID: CFragClosureID; connectionID: CFragConnectionID; fragLocator: CFragSystem7Locator; libName: StringPtr; reservedA: UInt32; { ! Must be zero! } END; CFragInitBlock = CFragSystem7InitBlock; CFragInitBlockPtr = ^CFragInitBlock; {$ENDC} CFragInitFunction = ProcPtr; { FUNCTION CFragInitFunction((CONST)VAR initBlock: CFragInitBlock): OSErr; C; } CFragTermProcedure = ProcPtr; { PROCEDURE CFragTermProcedure; C; } { § =========================================================================================== Old Name Spellings ================== ------------------------------------------------------------------------------------------- We've tried to reduce the risk of name collisions in the future by introducing the phrase "CFrag" into constant and type names. The old names are defined below in terms of the new. } {$IFC OLDROUTINENAMES } ConnectionID = CFragConnectionID; LoadFlags = CFragLoadOptions; SymClass = CFragSymbolClass; InitBlock = CFragInitBlock; InitBlockPtr = ^InitBlock; {$IFC NOT FOR_OPAQUE_SYSTEM_DATA_STRUCTURES } MemFragment = CFragSystem7MemoryLocator; MemFragmentPtr = ^MemFragment; DiskFragment = CFragSystem7DiskFlatLocator; DiskFragmentPtr = ^DiskFragment; SegmentedFragment = CFragSystem7SegmentedLocator; SegmentedFragmentPtr = ^SegmentedFragment; FragmentLocator = CFragSystem7Locator; FragmentLocatorPtr = ^FragmentLocator; CFragHFSMemoryLocator = CFragSystem7MemoryLocator; CFragHFSMemoryLocatorPtr = ^CFragHFSMemoryLocator; CFragHFSDiskFlatLocator = CFragSystem7DiskFlatLocator; CFragHFSDiskFlatLocatorPtr = ^CFragHFSDiskFlatLocator; CFragHFSSegmentedLocator = CFragSystem7SegmentedLocator; CFragHFSSegmentedLocatorPtr = ^CFragHFSSegmentedLocator; CFragHFSLocator = CFragSystem7Locator; CFragHFSLocatorPtr = ^CFragHFSLocator; {$ENDC} CONST kPowerPCArch = 'pwpc'; kMotorola68KArch = 'm68k'; kAnyArchType = $3F3F3F3F; kNoLibName = 0; kNoConnectionID = 0; kLoadLib = $0001; kFindLib = $0002; kNewCFragCopy = $0005; kLoadNewCopy = $0005; kUseInPlace = $80; kCodeSym = 0; kDataSym = 1; kTVectSym = 2; kTOCSym = 3; kGlueSym = 4; kInMem = 0; kOnDiskFlat = 1; kOnDiskSegmented = 2; kIsLib = 0; kIsApp = 1; kIsDropIn = 2; kFullLib = 0; kUpdateLib = 1; kWholeFork = 0; kCFMRsrcType = 'cfrg'; kCFMRsrcID = 0; kSHLBFileType = 'shlb'; kUnresolvedSymbolAddress = 0; kPowerPC = 'pwpc'; kMotorola68K = 'm68k'; {$ENDC} {$ALIGN RESET} {$POP} {$SETC UsingIncludes := CodeFragmentsIncludes} {$ENDC} {__CODEFRAGMENTS__} {$IFC NOT UsingIncludes} END. {$ENDC}